Skip to content

Make setup wizard resilient to richer gateway protocol steps#824

Merged
shanselman merged 2 commits into
openclaw:mainfrom
bkudiess:bkudiess-wizard-protocol-resilience
Jun 26, 2026
Merged

Make setup wizard resilient to richer gateway protocol steps#824
shanselman merged 2 commits into
openclaw:mainfrom
bkudiess:bkudiess-wizard-protocol-resilience

Conversation

@bkudiess

@bkudiess bkudiess commented Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Make the gateway setup wizard handle progress/status and action-style protocol steps without getting stuck.
  • Share step classification, URL/code formatting, and auth-aware timeout logic between headless setup and the WinUI wizard.
  • Preserve raw option values for unknown choice-style steps and harden gateway restart replay.

Fix details

  • Progress and non-interactive steps now acknowledge the current step with sessionId + answer.stepId, matching the gateway wizard.next contract.
  • Added WizardNextPayload plus regression tests showing that session-only polling repeats the current step, while acknowledgement advances it.
  • Progress polling remains bounded by per-step and aggregate caps.

Behavioral proof

I ran the branch locally through setup and the real gateway wizard. The machine's WSL online Ubuntu install path returned TRUST_E_BAD_DIGEST, so the proof run used a temporary uncommitted local-rootfs override to get past WSL distro creation. No rootfs override changes are included in this PR.

Observed live wizard flow:

OpenClaw setup
Config handling
QuickStart
Model/auth provider
Default model
Model check
How channels work
Select channel (QuickStart)
Web search
Search provider
Skills status
Configure skills now? (recommended)
Hooks
Enable hooks?
Grant permissions

Representative live UI/log evidence:

Docs: https://docs.openclaw.ai/channels/pairing
Live gateway output
Updated config: ~/.openclaw/openclaw.json
Workspace OK: ~/.openclaw/workspace
Sessions OK: ~/.openclaw/agents/main/sessions

[WS] hello-ok ... methods include wizard.start, wizard.next, wizard.cancel, wizard.status
step.completed: verify-e2e -> Success
Pipeline completed successfully in 166.2s

Screenshots captured locally for review artifacts:

openclaw-live-wizard-first-step.png
openclaw-live-wizard-after-config-handling.png
openclaw-live-wizard-after-channel-info.png
openclaw-live-wizard-after-channel-skip.png
openclaw-live-wizard-after-search-skip.png
openclaw-live-wizard-after-hooks-skip.png
openclaw-live-final-permissions.png

Focused protocol harness

A local harness also verified the protocol helper behavior directly:

classify progress: Progress
progress continues without answer: True
classify action without options: NonInteractive
action without options continues: True
classify action with options: RequiresAnswer
url line kind: Url
url highlight: https://example.test/device
code line kind: Code
code highlight: WDJB-MJHT
auth timeout: 300000
ordinary timeout: 30000
unknown-with-options wire kind: Number
unknown-with-options wire value: 42

Protocol/source proof

Checked against upstream OpenClaw gateway/macOS sources:

  • packages/gateway-protocol/src/schema/wizard.ts defines progress and action, options[].value as Unknown, initialValue as Unknown, and optional sensitive / executor.
  • src/wizard/session.ts exposes the runtime step union and uses unknown option values.
  • apps/macos/Sources/OpenClaw/OnboardingWizard.swift consumes the same wizard start/next model and preserves selected option values through AnyCodable.

Validation

  • ./build.ps1 — all projects passed.
  • dotnet test ./tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj — 331 passed.
  • dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj — 1163 passed.
  • dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-build — 2422 passed / 29 skipped on rerun.

Notes

  • The wizard protocol is forward-only; this PR does not add a back-step operation.
  • The temporary local-rootfs setup override used for proof is not part of this PR.

@clawsweeper

clawsweeper Bot commented Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown

Codex review: needs maintainer review before merge. Reviewed June 25, 2026, 10:47 PM ET / 02:47 UTC.

Summary
The PR updates the headless setup runner and WinUI wizard to classify richer gateway wizard steps, acknowledge progress/non-interactive steps, share formatting and timeout helpers, preserve raw option values for unknown choice prompts, and add focused SetupEngine tests.

Reproducibility: yes. source-level: current main documents Progress wizard steps but the headless runner advances no-answer steps with sessionId only, while the PR adds answer-envelope acknowledgement coverage. I did not run live Windows setup in this read-only review.

Review metrics: 3 noteworthy metrics.

  • Changed setup callers: 2 production callers changed. Both headless setup and the WinUI wizard now share the richer wizard-step behavior, so setup-state review matters before merge.
  • Changed surface: 10 files, +775/-151. The diff is broad enough that protocol and upgrade proof matter before merge.
  • Focused tests added: 4 test files added. New coverage targets the classifier, acknowledgement envelope, formatting, and timeout helpers that carry the protocol change.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • none.

Mantis proof suggestion
A visible Windows setup wizard pass would materially help maintainers verify progression through gateway progress/action steps. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify the Windows setup wizard advances through gateway progress/action steps to the permissions page without looping.

Risk before merge

  • [P1] The PR changes how both setup callers advance wizard sessions; if the live gateway expects a different acknowledgement envelope for progress/action steps, first-run setup could still loop or block.
  • [P1] Restart replay intentionally starts a new gateway wizard session and resets local counters after disconnect; maintainers should confirm that losing partially completed wizard session state is acceptable for this setup path.
  • [P1] The latest GitHub status check rollup still showed several Build and Test jobs in progress for head 97a87d7, so merge should wait for normal required checks to finish.

Maintainer options:

  1. Accept After Setup-Focused Review (recommended)
    Maintainers can land once they confirm the final head's acknowledgement, polling, and restart replay behavior matches the live gateway setup contract.
  2. Ask For One More Live Repeat Proof
    If maintainers want lower risk after the force-push, ask for a short redacted log or recording showing a live progress/action repeat advancing through the acknowledgement path.
  3. Pause If Gateway Contract Differs
    If the gateway expects another shape for progress/action steps, pause this PR and align the protocol contract before changing both clients.

Next step before merge

  • No automated repair is queued; the remaining action is maintainer review of setup session-state and availability risk before merge.

Security
Cleared: The diff changes C# setup wizard parsing, rendering, timeout, polling, and tests; no concrete security or supply-chain regression was found.

Review details

Best possible solution:

Land the shared wizard-protocol handling after maintainers accept the acknowledgement, polling, and restart-replay contract; keep Back-navigation semantics tracked separately.

Do we have a high-confidence way to reproduce the issue?

Yes, source-level: current main documents Progress wizard steps but the headless runner advances no-answer steps with sessionId only, while the PR adds answer-envelope acknowledgement coverage. I did not run live Windows setup in this read-only review.

Is this the best way to solve the issue?

Yes. Sharing classification, acknowledgement shaping, formatting, and timeout policy across both setup callers is the narrow maintainable fix for this protocol-resilience gap.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9447c0f76b1f.

Label changes

Label justifications:

  • P2: This is a normal-priority first-run setup resilience fix with limited blast radius and no emergency signal.
  • merge-risk: 🚨 session-state: The PR changes wizard session advancement, acknowledgement envelopes, progress counters, and restart replay behavior.
  • merge-risk: 🚨 availability: A bad wizard progression path could loop or block first-run setup on richer gateway progress/action steps.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (logs): The PR body includes copied live setup flow/log output reaching permissions plus focused protocol-harness output for the changed wizard behavior.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied live setup flow/log output reaching permissions plus focused protocol-harness output for the changed wizard behavior.
Evidence reviewed

What I checked:

  • Repository policy read: AGENTS.md was read fully; its setup/onboarding guidance led this review through the setup wizard sources and onboarding docs, while validation commands were not run because this cleanup review is read-only. (AGENTS.md:1, 9447c0f76b1f)
  • Current docs define the affected wizard surface: Current main documents the gateway-driven wizard as wizard.start / wizard.next and includes Progress as a supported step type, so richer step handling is inside the existing setup contract. (docs/ONBOARDING_WIZARD.md:29, 9447c0f76b1f)
  • Current main still has the session-only no-answer path: The current headless runner sends only sessionId when ResolveAnswer has no explicit answer, which is the central path this PR replaces for acknowledgement-only protocol steps. (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:147, 9447c0f76b1f)
  • PR head adds bounded progress acknowledgement in headless setup: The PR head classifies progress steps, bounds progress polling, and advances progress with WizardNextPayload.Acknowledge(sessionId, parsed.StepId). (src/OpenClaw.SetupEngine/SetupWizardRunner.cs:168, 97a87d7413e3)
  • PR head adds matching WinUI progress/non-interactive handling: The WinUI page loops through progress steps with bounded polling and uses the acknowledgement envelope for progress and non-interactive steps. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:241, 97a87d7413e3)
  • Focused regression coverage added: The PR adds tests for acknowledgement serialization/current-step advancement, step classification, timeout budget, and message formatting around the new protocol behavior. (tests/OpenClaw.SetupEngine.Tests/WizardNextPayloadTests.cs:8, 97a87d7413e3)

Likely related people:

  • the99missedcalls: Blame and file history show the current SetupWizardRunner and much of WizardPage's core wizard flow dating to commit ff38d84. (role: introduced current wizard runner behavior; confidence: high; commits: ff38d8499c48; files: src/OpenClaw.SetupEngine/SetupWizardRunner.cs, src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs)
  • bkudiess: Current main includes this contributor's recent WSL gateway dependency-recovery work in WizardPage and onboarding docs, plus the merged option wire-value work adjacent to this PR's protocol surface. (role: recent adjacent wizard contributor; confidence: high; commits: 1e6951331f1c, ac169adab42e; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, docs/ONBOARDING_WIZARD.md, src/OpenClaw.SetupEngine/WizardAnswerBuilder.cs)
  • Christine Yan: Recent merged history touches WizardPage, WizardConsoleTail, and OpenClawGatewayClient in the install-wizard rendering/protocol-adjacent area. (role: recent area contributor; confidence: medium; commits: 992da748c31b; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine.UI/WizardConsoleTail.cs, src/OpenClaw.Shared/OpenClawGatewayClient.cs)
  • shanselman: Git history shows recurring setup-wizard merge commits, and PR metadata shows this person authored the polling-budget hardening commit on the current PR head. (role: recent adjacent merger and PR head hardening author; confidence: medium; commits: 1ec5d24a0b7a, b2f537bbe285, 97a87d7413e3; files: src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs, src/OpenClaw.SetupEngine/WizardTimeouts.cs)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 session-state 🚨 Merging this PR could lose, corrupt, stale, or mis-associate session or agent state. merge-risk: 🚨 availability 🚨 Merging this PR could cause crashes, hangs, restart loops, stalls, or process outages. labels Jun 25, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jun 25, 2026
Open
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Jun 25, 2026
@bkudiess

bkudiess commented Jun 25, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added proof: sufficient Contributor real behavior proof is sufficient. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jun 25, 2026
@bkudiess bkudiess marked this pull request as ready for review June 25, 2026 23:16
@bkudiess bkudiess force-pushed the bkudiess-wizard-protocol-resilience branch from 535c25d to ca697b5 Compare June 25, 2026 23:31
@bkudiess

bkudiess commented Jun 25, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jun 25, 2026
@shanselman shanselman force-pushed the bkudiess-wizard-protocol-resilience branch from ca697b5 to 21c31b7 Compare June 26, 2026 02:24
Copilot and others added 2 commits June 25, 2026 19:40
@shanselman
Wizard protocol resilience: progress/non-interactive steps, auth prom…
8b12acd 
…pts, restart hardening

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@shanselman
Harden wizard progress polling budget
97a87d7 
Allow a single long-running gateway progress step to use the full bounded progress budget instead of failing after the previous shorter per-step cap. Share the progress constants between the setup runner and UI and cover the intended budget in tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@shanselman shanselman force-pushed the bkudiess-wizard-protocol-resilience branch from 21c31b7 to 97a87d7 Compare June 26, 2026 02:43
@shanselman shanselman merged commit 84d2e6a into openclaw:main Jun 26, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

merge-risk: 🚨 availability 🚨 Merging this PR could cause crashes, hangs, restart loops, stalls, or process outages. merge-risk: 🚨 session-state 🚨 Merging this PR could lose, corrupt, stale, or mis-associate session or agent state. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@bkudiess @shanselman